//+------------------------------------------------------------------+
//|                                                      Picture.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "WndObj.h"                                  // 窗口对象基类（提供基础控件能力）
#include <ChartObjects/ChartObjectsBmpControls.h>    // 图表位图控件类（包含 CChartObjectBmpLabel）

//+------------------------------------------------------------------+
//| CPicture 类：MQL5 图片控件类                                      |
//| 核心能力：封装图表对象 CChartObjectBmpLabel，提供位图图像显示功能，  |
//|           支持边框宽度设置和图片文件关联，用于在图表上展示自定义图像  |
//| 适用场景：图标显示、Logo展示、自定义按钮背景、装饰性图像等            |
//+------------------------------------------------------------------+
class CPicture : public CWndObj
  {
private:
   CChartObjectBmpLabel m_picture;          // 图表位图对象（底层实现，负责绘制图片）
   int               m_border;              // 边框宽度（像素，0 表示无边框）
   string            m_bmp_name;            // 位图文件名（需放在终端的 MQL5\Files 目录下）

public:
   //----------------------------------------------------------------
   // 构造与析构函数
   //----------------------------------------------------------------
   /**
    * @brief 构造函数：初始化图片控件默认状态
    * @details 初始化边框宽度为 0（无边框），位图文件名为空（未关联图片）
    */
                     CPicture(void);

   /**
    * @brief 析构函数：清理图片控件资源
    * @details 依赖父类 CWndObj 的析构逻辑，自动释放底层图表对象 m_picture
    */
                    ~CPicture(void);

   //----------------------------------------------------------------
   // 控件创建：在图表上创建图片控件
   //----------------------------------------------------------------
   /**
    * @brief 在指定图表位置创建图片控件
    * @param chart [in] 目标图表ID（0 表示当前活跃图表）
    * @param name [in] 控件唯一标识名（图表内不可重复）
    * @param subwin [in] 绑定的子窗口编号（0 = 主窗口，≥1 = 指标子窗口）
    * @param x1 [in] 左上角X坐标（像素，相对于图表窗口）
    * @param y1 [in] 左上角Y坐标（像素）
    * @param x2 [in] 右下角X坐标（像素，用于计算控件宽度）
    * @param y2 [in] 右下角Y坐标（像素，用于计算控件高度）
    * @return bool - 创建结果：true=成功（父类初始化+底层对象创建完成），false=失败
    */
   virtual bool      Create(const long chart,const string name,const int subwin,const int x1,const int y1,const int x2,const int y2);

   //----------------------------------------------------------------
   // 边框配置：设置/获取边框宽度
   //----------------------------------------------------------------
   /**
    * @brief 获取当前边框宽度
    * @return int - 边框宽度（像素，0 表示无边框）
    */
   int               Border(void) const;

   /**
    * @brief 设置图片控件的边框宽度
    * @param value [in] 目标边框宽度（像素，≥0）
    * @return bool - 设置结果：true=成功（更新底层对象边框宽度），false=失败
    */
   bool              Border(const int value);

   //----------------------------------------------------------------
   // 图片配置：设置/获取关联的位图文件
   //----------------------------------------------------------------
   /**
    * @brief 获取当前关联的位图文件名
    * @return string - 位图文件名（空字符串表示未关联图片）
    */
   string            BmpName(void) const;

   /**
    * @brief 设置图片控件关联的位图文件
    * @param name [in] 位图文件名（需位于终端的 MQL5\Files 目录或其子目录）
    * @return bool - 设置结果：true=成功（图片文件存在并关联），false=失败（文件不存在或路径错误）
    * @note 支持的图片格式：BMP（24位真彩色）
    */
   bool              BmpName(const string name);

protected:
   //----------------------------------------------------------------
   // 控件生命周期事件处理器（保护，仅子类可重写）
   //----------------------------------------------------------------
   /**
    * @brief 创建完成事件回调（控件创建后触发）
    * @return bool - 处理结果：true=成功（底层对象初始化完成），false=失败
    */
   virtual bool      OnCreate(void);

   /**
    * @brief 显示事件回调（控件从隐藏变为显示时触发）
    * @return bool - 处理结果：true=成功（在所有时间帧显示图片），false=失败
    */
   virtual bool      OnShow(void);

   /**
    * @brief 隐藏事件回调（控件从显示变为隐藏时触发）
    * @return bool - 处理结果：true=成功（在所有时间帧隐藏图片），false=失败
    */
   virtual bool      OnHide(void);

   /**
    * @brief 移动事件回调（控件位置变化时触发）
    * @return bool - 处理结果：true=成功（更新底层对象位置），false=失败
    */
   virtual bool      OnMove(void);

   /**
    * @brief 属性变化事件回调（控件属性更新时触发）
    * @return bool - 处理结果：true=成功（同步边框宽度和图片文件到底层对象），false=失败
    */
   virtual bool      OnChange(void);
  };
//+------------------------------------------------------------------+